Add CLI options reference documentation#13930
Conversation
psf-chronographer
bot
added
the
bot:chronographer:provided
|
Hi @FazeelUsmani, can you open an issue with your proposal? It will allow us to have a place to discuss the idea not in the context of a specific PR. |
|
Sure, let me open |
|
Thanks for the update! Quick preview link: https://pytest--13930.org.readthedocs.build/en/13930/reference/reference.html#command-line-flags Please see my comment below. When a flag has short and long (or alternatives) it is rendered as: 
First, I think it would be nicer to render the alternatives in a single line, separated by commas. It makes it clearer they are alternatives, and not just something that we forgot to document. Second, I think we should only have one canonical I think some of the options can have better links to places in the docs which discuss them, but I realize this is hard work, so not a blocker, maybe can be improved in the future. Another thing we can improve in the future is to go over the docs and when a flag is mentioned make it a hyperlink using The Also, I think it would be better if the |
I'm OK with either, TBH. |
|
@nicoddemus Done ✅ |
bluetech
force-pushed
the
add-cli-options-docs
branch
from
30dacdf to
f443bf2
Compare
|
I updated the PR:
When I have time I will add more cross refs, then it should be good to go. |
bluetech
force-pushed
the
add-cli-options-docs
branch
from
f443bf2 to
3784255
Compare
nicoddemus
left a comment
nicoddemus
left a comment
There was a problem hiding this comment.
Looks great, thanks @FazeelUsmani and @bluetech!
|
I added some cross-refs and back-refs. Will merge once CI passes. |
|
I think we can backport this. |
bluetech
added
the
backport 9.0.x
Backport to 9.0.x: 💚 backport PR created✅ Backport PR branch: Backported as #14013 🤖 @patchback |
Co-authored-by: Ran Benita <ran@unusedvar.com> (cherry picked from commit 922b603)
…22b60377a38238b282c062e9589fdbe7eac1804/pr-13930 [PR #13930/922b6037 backport][9.0.x] Add CLI options reference documentation
3 participants
Addresses #13973
Summary
Previously, pytest command-line options were only visible via
pytest --help, making them difficult to discover and browse online. This PR adds a dedicated CLI options reference page to improve discoverability and provide a better documentation experience.Changes
Added a new documentation page (
doc/en/how-to/cli-options.rst) that organizes commonly used pytest CLI options into logical categories:-k,-m,-x,--maxfail,--lf,--ff,--sw)-v,-q,--tb,-l,-r)--junit-xml,--durations,-s)--collect-only,--pyargs,--ignore)--pdb,--trace,--fixtures,--setup-show)-c,--basetemp,-o)--log-cli-level,--log-level,--log-file)--disable-warnings,-W)Each section includes clear examples, brief explanations, and cross-references to related documentation. The page also links to the complete command-line flag reference for users who need the exhaustive list.
Files Changed
doc/en/how-to/cli-options.rst- new CLI options reference page (307 lines)doc/en/how-to/index.rst- added the new page to the table of contentschangelog/4492.doc.rst- changelog entryTesting
The documentation was successfully built using Sphinx with no errors. All cross-references are valid and the generated HTML renders correctly.